PsL Monthly 1993 December

home *** CD-ROM | disk | FTP | other *** search

/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / c / cxref.exe / CXREF.DOC < prev next >

Wrap

Text File | 1992-02-24 | 19.6 KB | 537 lines

C xref - C language cross-reference utility. v2.0 C xref The C language cross reference utility. (c) 1992 by David Archibald. C xref - C language cross-reference utility. v2.0 Table of Contents Introduction: Registration information............... 101 System requirements.................... 102 What C xref does....................... 103 Program output: Global variables and constants......... 201 Summary list of functions.............. 202 Verbose list of functions.............. 203 Function tree.......................... 204 Running C xref: The command line syntax................ 301 The module names....................... 302 The -x command......................... 303 The -t command......................... 304 The -s command......................... 305 The -w command......................... 306 The -l command......................... 307 The -i command......................... 308 The -n command......................... 309 Command line examples.................. 310 The reserved word file: RES_WORD.TXT........ 401 What C xref ignores......................... 501 C xref - C language cross-reference utility. v2.0 101 Registration information. C xref is a Shareware program, and copies of this program and it's documentation may be freely distributed. Note: C xref and this document are copyrighted and may not be modified in any manner. Individual copies may be licensed for $20. (Site licenses are available for commercial use. Please write for details.) After registering you will be sent the latest version of C xref, and, as they become available, any future updates. C xref - C language cross-reference utility. v2.0 Order Form Registration fee Fee $ 20.00 (Michigan residents please add 4% sales tax) Tax .80 Total $ _______ Name:___________________________________________________ Company:________________________________________________ Address:________________________________________________ :________________________________________________ :________________________________________________ Disk size: 5 1/4:_____ 3 1/2:_____ Send to: DA Software 3717 Aldon Lane Flint, MI 48506 (If you have any suggestions or comments about C xref, please include them.) Comments: C xref - C language cross-reference utility. v2.0 102 System requirements. Config.sys file: The "file" statement in your config.sys file must equal at least 20. If it doesn't, then using EDLIN, or another ASCII text editor, change the "file" statement in your config.sys file so that it reads "file=20". Memory limits: There is no minimum memory, but the number of modules you can cross-reference is dependent on the amount of memory you have. If C xref runs out of memory it will output an error message, and terminate. 103 What it does. C xref is a cross-reference utility program for the C programming language. It will read any number of your C text modules and send the following to standard output: o A list of the module's global variables and constants, along with the line numbers they appear on. o A summary listing of module's functions. o A verbose list of all the module's functions that includes: the name of the module it originates in, line of origin, users, callers, and what local and global variables appear in the function. o A tree that displays all of the functions calling hierarchy. Note: Remember, you can use DOS redirection to send the output else where; i.e. >LPT1. C xref - C language cross-reference utility. v2.0 201 Global variables and constants. C xref assumes that anything declared outside a function's boundaries (from the function name to the function's closing brace) is a global variable or constant. The global variable and constant cross-reference has the following format: variable name [type] {module name} which line numbers in this module the variable appears on. Sample output: char_pnt [char] {example.c } 1 {explfile.c } 10 11 16 28 35 42 cnt [int] {example.c } 4 11 32 {explfile.c } 8 14 202 Summary list of functions. The summary list has the following format: {module name} : line-of-origin : function name() [type] Note: a line-of-origin of [NONE] indicates that the function was not in any of the modules cross-referenced. Sample output: {explfile.c } : 32 : is_it_a_comma() [int] {example.c } : 7 : main() [void] {explfile.c } : 39 : not_comma() [char] {example.c } : 25 : open_file() [FILE] C xref - C language cross-reference utility. v2.0 203 Verbose list of functions. The verbose list of functions has the following format: function name [type] : {module name} : line-of-origin USERS: {module name} the line numbers in this module that reference this function. CALLS: {module name} function name() {module} func1() LOCAL VARIABLES: variable name [type]. the line numbers in this function it appears on. GLOBAL VARIABLES: variable name [type]. the line numbers in this function it appears on. As with the summary listing, a line-of-origin of [NONE] indicates that a function was referenced, but did not appear in any of the modules cross-referenced. USERS are the line numbers in a module that call this function. CALLS are other functions that this function references. LOCAL VARIABLES are any variable or constant that falls between a function's name and it's closing brace. Note: As with your C compiler, when a local and global variable have the same name, the global variable is hidden and C xref cross-references it as a local variable. GLOBAL VARIABLES are a list of any global variables or constants that appear in this function. C xref - C language cross-reference utility. v2.0 Sample verbose output: =============================================================================== main() [void] : {example.c} : 7 =============================================================================== USERS: [NONE] ------------------------------------------------------------------------------- CALLS: {example.c } close_file() {explfile.c } not_comma() {example.c } get_input() {example.c } open_file() ------------------------------------------------------------------------------- LOCAL VARIABLES: argc [int] 7 10 argv [char] 7 9 column [int] 13 19 file_name [char] 12 17 file_pnt [FILE] 14 18 21 row [int] 13 19 ------------------------------------------------------------------------------- GLOBAL VARIABLES: cnt [int] {example.c } 11 =============================================================================== not_comma() [char] : {explfile.c} : 39 =============================================================================== USERS: {explfile.c } 13 ------------------------------------------------------------------------------- CALLS: [NONE] ------------------------------------------------------------------------------- LOCAL VARIABLES: [NONE] ------------------------------------------------------------------------------- GLOBAL VARIABLES: char_pnt [char] {explfile.c} 42 C xref - C language cross-reference utility. v2.0 204 Function tree. The function tree option generates a tree representation of all of module's function calls (or more simply stated: who's calling who). The following is a sample tree for two modules: example.c :main example.c :|_close_file example.c :|_output_char example.c :|_get_input explfile.c :| |_not_comma explfile.c :| |_is_it_a_comma explfile.c :| |_is_it_a_comma* :| example.c :|_open_file Note: An '*' following a function name indicates that this is a recursive function call. C xref - C language cross-reference utility. v2.0 301 The command line syntax. cxref [-x t i[p path;path...] n s w l] sourcefilespec1 [sourcefilespec2...] Note: A space must separate each command. 302 Module names. C xref will accept any legal DOS file name. Standard DOS pattern checking is supported ('?' and '*'). Note: Upper or lower case letters can be used with any of the following commands. 303 The -x command. When the 'x' command is entered, everything except the function tree is output. 304 The -t command. With the 't' command, only the function tree is output- -nothing else. 305 The -s command. With the 's' command, only the function summary is output- -all other output is suppressed. 306 The -w command. The default line width for output is 80 characters, but with the 'w' command you can set the line width to 132 characters (useful if you have a wide carriage printer). 307 The -l command. With the 'l' command you can add identifiers from the cross- referenced modules to the RES_WORD.TXT file (C xref ignores anything in a module that appears in this file. See section 401). C xref - C language cross-reference utility. v2.0 The function names and global variables will be output one at a time. After an identifier is output you may select one of three options: o Press 'a' to add the item to the RES_WORD.TXT file. o Press 'q' to quit and stop adding to the file. o Press any other key to skip the item. 308 The -i command. The 'i' command lets you to cross-reference the "include" files in your modules. This command only cross-references those include files that are enclosed in "<>". C xref keeps track of the names of include files, so that a file is only cross-referenced once. It also cross-references nested include files up to 15 files deep. Cxref always looks in the current directory (i.e. the directory in which the current module is located) for an include file, but you can enter alternate path names. For example: -ip c:\dos\;c:\prg\text\ Each path name must be separate by a ";" and the -i command must be followed by a "p" (if you are not entering an alternate path name, then do not include the "p"). 309 The -n command. C xref automatically cross-references include files enclosed in double quotes (i.e. #include "mydef.h"), but you can disable this with the 'n' command. C xref searches the current directory for the include file, but if it is unfound, and the '-i' command was entered, it will search any alternate path names that follow it. Note: If you use identifiers in place of file names in your include statements, then C xref can not cross-reference them. For example: #define F_NAME "mydef.h" #include F_NAME /* won't cross-reference! */ C xref - C language cross-reference utility. v2.0 310 Command line examples. cxref -ip c:\dos\;c:\prg\text\ -w mod??.c This command line will: o Output a complete cross-reference listing. o Cross-reference all include files, looking for them in the default, "c:\dos\", and "c:\prg\text\" directories. o Output in 132 column width. o Cross-reference any file that matches the file name pattern "mod??.c". cxref -t -l c:\prg\*.c a:\text\bigprg?.* This command line will: o Only output a function tree. o Output the global and function identifiers and give you the opportunity to add them to the RES_WORD.TXT file. o Cross-reference all files in the sub-directories "c:\prg\*.c" and "a:\text\bigprg?.*" that match the name patterns "*.c" and "bigprg?.*". Note: if you run C xref with an empty command line (i.e. cxref <CR>) you will get a short description of the command switches. C xref - C language cross-reference utility. v2.0 401 The reserved word file: RES_WORD.TXT If C xref included references to C function calls (printf, etc.) or it's reserved words, the output would soon become pretty long and messy. To prevent this, C xref reads the RES_WORD.TXT file when executed, and ignores any words in your modules that match those from the file. RES_WORD.TXT is an ASCII text file where each reserved word is followed by a new line character. The line length is limited to 80 characters. Anything following an '*' in the first column is considered a comment, and is ignored (the '*' MUST be in the first column). The reserved word list is stored by C xref in a binary tree, so the best efficiency (a more balanced tree) is achieved when you do not build the RES_WORD.TXT file in alphabetical order. The RES_WORD.TXT file included with this program has all of C's reserved words and ANSI function calls, and a number of common defines (e.g. TRUE, FALSE, EOF, etc.). The file also includes the function calls from Turbo C (if you are using another compiler you can simply delete these, and add the function calls of your compiler). The RES_WORD.TXT file must be in the same directory as C xref. 501 What C xref ignores. C xref ignores: o Anything enclosed by single or double quotes. o All comments. o Anything that matches the contents of the RES_WORD.TXT file. ----------------end-of-author's-documentation--------------- Software Library Information: This disk copy provided as a service of Public (software) Library We are not the authors of this program, nor are we associated with the author in any way other than as a distributor of the program in accordance with the author's terms of distribution. Please direct shareware payments and specific questions about this program to the author of the program, whose name appears elsewhere in this documentation. If you have trouble getting in touch with the author, we will do whatever we can to help you with your questions. All programs have been tested and do run. To report problems, please use the form that is in the file PROBLEM.DOC on many of our disks or in other written for- mat with screen printouts, if possible. PsL cannot debug pro- programs over the telephone, though we can answer questions. Disks in the PsL are updated monthly, so if you did not get this disk directly from the PsL, you should be aware that the files in this set may no longer be the current versions. Also, if you got this disk from another vendor and are having prob- lems, be aware that some files may have become corrupted or lost by that vendor. Get a current, working disk from PsL. For a copy of the latest monthly software library newsletter and a list of the 4,000+ disks in the library, call or write Public (software) Library P.O.Box 35705 - F Houston, TX 77235-5705 1-800-2424-PSL MC/Visa/AmEx/Discover Outside of U.S. or in Texas or for general information, Call 1-713-524-6394 PsL also has an outstanding catalog for the Macintosh.